============
Installation
============

REQUIREMENTS
============

* A Unix-like operating system (e.g., \*BSD, illumos, Linux, or macOS).

* Python_ ≥ v3.9.

* The `Package Installer for Python`_ (pip)

* Optionally, the Python module cryptography_ (see EXTRAS_ below).

* Optionally, the Python module dnspython_ (see EXTRAS_ below).


DOWNLOAD
========

Download the most recent release:

.. code:: bash

    curl -O https://codeberg.org/odkr/sievemgr/releases/download/v0.6.1/sievemgr-0.6.1.tgz

Optionally, check whether the tarball has been tampered with:

.. code:: bash

    curl -O https://codeberg.org/odkr/sievemgr/releases/download/v0.6.1/sievemgr-0.6.1.tgz.asc
    gpg --recv-key 8975B184615BC48CFA4549056B06A2E03BE31BE9
    gpg --verify sievemgr-0.6.1.tgz.asc

Unpack the tarball:

.. code:: bash

    tar -xzf sievemgr-0.6.1.tgz

Go to the top-level directory of the repository:

.. code:: bash

    cd sievemgr-0.6.1

.. caution::
    The following commands require that
    the repository is your working directory.


INSTALLATION
============

Home directory
--------------

.. code:: bash

    make userinstall

The manual pages are copied to :file:`~/.local/share/man`.
Consult the manual of your system's :command:`man` or your shell
on how to add that directory to your :envvar:`MANPATH`.

The Bash completion script is copied to
:file:`~/.local/share/bash-completion/completions`.

Install the cryptography_ Python module:

.. code:: bash

    python3 -mpip install --user cryptography


System-wide
-----------

Store the installation directory in `$venvdir`:

.. code:: bash

    venvdir=/opt/odkr/sievemgr

Create a virtual environment in `$venvdir`:

.. code:: bash

    python3 -mvenv "${venvdir:?}"

Install SieveManager to the virtual environment:

.. code:: bash

    make venvdir="${venvdir:?}" venvinstall

Install the cryptography_ module to the virtual environment:

.. code:: bash

    "${venvdir:?}/bin/pip" install cryptography

Symlink :command:`sievemgr` into a directory in the system's :envvar:`PATH`:

.. code:: bash

    ln -s "${venvdir:?}/bin/sievemgr" /usr/local/bin

.. tip::
    Install SieveManager to `$venvdir`, but copy the manual pages
    to :file:`/usr/local/share/man`, and the Bash completion script to
    :file:`/usr/local/share/bash-completion/completions`:

    .. code:: bash

        make venvdir="$venvdir" prefix=/usr/local venvinstall


Manual
------

SieveManager is but a Python script.

It can also be installed by being copied into
a directory that is in your :envvar:`PATH`.

For example:

.. code:: bash

    install sievemgr.py ~/.local/bin/sievemgr


DE-INSTALLATION
===============

.. code:: bash

    make uninstall


EXTRAS
======

cryptography
------------

Checking whether a server's TLS certificate has been revoked requires
the non-standard Python module cryptography_, which can be installed with:

.. code:: bash

    python3 -mpip install cryptography

.. important::
    cryptography_ should be installed.


dnspython
---------

Resolving DNS SRV records requires the non-standard Python module dnspython_,
which can be installed with:

.. code:: bash

    python3 -mpip install dnspython

.. note::
   ManageSieve servers typically do *not* have SRV records.
   SieveManager works well without dnspython.


Bash completion
---------------

The Bash completion script that SieveManager ships with is written
with the bash-completion_ package in mind. But it can also be loaded
by adding, for example,

.. code:: bash

    source "$HOME/.local/share/bash-completion/completions/sievemgr.bash"

to your :file:`.bashrc`.

.. _bash-completion: https://github.com/scop/bash-completion


PACKAGING
=========

See :doc:`packaging` for an example how to
package SieveManager for Debian_.


.. _Debian: https://www.debian.org

.. _`Package Installer for Python`: https://pypi.org/project/pip/

.. _Python: https://www.python.org/

.. _cryptography: https://cryptography.io

.. _dnspython: https://www.dnspython.org/
